.TH "Call Home" 3 "Fri Apr 15 2016" "Version 0.10.0-146_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Call Home \- 
.PP
libnetconf's functions implementing NETCONF Call Home (both SSH and TLS) mechanism\&. More information can be found at \fBCall Home\fP page\&.  

.SS "Functions"

.in +1c
.ti -1c
.RI "struct nc_session * \fBnc_callhome_accept\fP (const char *username, const struct nc_cpblts *cpblts, int *timeout)"
.br
.RI "\fIAccept incoming Call Home connection and create NETCONF session on it\&. \fP"
.ti -1c
.RI "int \fBnc_callhome_connect\fP (struct nc_mngmt_server *host_list, uint8_t reconnect_secs, uint8_t reconnect_count, const char *server_path, char *const argv[], int *com_socket)"
.br
.RI "\fIConnect NETCONF server to a management center (NETCONF client) using Call Home mechanism\&. \fP"
.ti -1c
.RI "int \fBnc_callhome_listen\fP (unsigned int port)"
.br
.RI "\fIStart listening on client side for incoming Call Home connection\&. \fP"
.ti -1c
.RI "int \fBnc_callhome_listen_stop\fP (void)"
.br
.RI "\fIStop listening on client side for incoming Call Home connection\&. \fP"
.ti -1c
.RI "struct nc_mngmt_server * \fBnc_callhome_mngmt_server_add\fP (struct nc_mngmt_server *list, const char *host, const char *port)"
.br
.RI "\fIAdd a new management server specification to the end of a list\&. \fP"
.ti -1c
.RI "int \fBnc_callhome_mngmt_server_free\fP (struct nc_mngmt_server *list)"
.br
.RI "\fIFree a management server description structure(s)\&. The function doesn't free only the item refered by given pointer, but the complete list of management servers is freed\&. \fP"
.ti -1c
.RI "struct nc_mngmt_server * \fBnc_callhome_mngmt_server_getactive\fP (struct nc_mngmt_server *list)"
.br
.RI "\fISearches for the item from the list, which was marked and used by the last call to \fBnc_callhome_connect()\fP to a successfully establish Call Home connection\&. \fP"
.ti -1c
.RI "int \fBnc_callhome_mngmt_server_rm\fP (struct nc_mngmt_server *list, struct nc_mngmt_server *remove)"
.br
.RI "\fIRemove the specified management server description from the list\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
libnetconf's functions implementing NETCONF Call Home (both SSH and TLS) mechanism\&. More information can be found at \fBCall Home\fP page\&. 


.SH "Function Documentation"
.PP 
.SS "struct nc_session* nc_callhome_accept (const char *username, const struct nc_cpblts *cpblts, int *timeout)"

.PP
Accept incoming Call Home connection and create NETCONF session on it\&. This function uses transport protocol set by \fBnc_session_transport()\fP\&. If NC_TRANSPORT_SSH (default value) is set, configure's --disable-libssh option cannot be used\&. If NC_TRANSPORT_TLS is set, configure's --enable-tls must be used
.PP
To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIusername\fP Name of the user to login to the server\&. The user running the application (detected from the effective UID) is used if NULL is specified\&. 
.br
\fIcpblts\fP NETCONF capabilities structure with capabilities supported by the client\&. Client can use \fBnc_session_get_cpblts_default()\fP to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter)\&. 
.br
\fItimeout\fP Timeout for waiting for incoming call home in milliseconds\&. Negative value means an infinite timeout, zero causes to return immediately\&. If a positive value is set and timeout is reached, NULL is returned and timeout is changed to 0\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Structure describing the NETCONF session or NULL in case of an error\&. NULL is also returned in case of timeout, but in that case also timeout value is changed to 0\&. 
.RE
.PP

.SS "int nc_callhome_connect (struct nc_mngmt_server *host_list, uint8_treconnect_secs, uint8_treconnect_count, const char *server_path, char *constargv[], int *com_socket)"

.PP
Connect NETCONF server to a management center (NETCONF client) using Call Home mechanism\&. Use \fBnc_session_transport()\fP function to specify which transport protocol should be used\&.
.PP
Note that reconnect_secs and reconnect_count parameters are used only before a connection is established, then the function returns\&. It's up to the caller to reconnect if the session goes down\&. It can be detected using returned PID\&.
.PP
To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIhost_list\fP List of management servers descriptions where the function will try to connect to\&. 
.br
\fIreconnect_secs\fP Time delay in seconds between connection attempts (even to the same server but it depends on reconnect_count)\&. See /netconf/ssh/call-home/applications/application/reconnect-strategy/interval-secs value in ietf-netconf-server YANG data model\&. 
.br
\fIreconnect_count\fP Number times the function tries to connect to a single server before moving on to the next server in the host_list\&. See /netconf/ssh/call-home/applications/application/reconnect-strategy/count-max value in ietf-netconf-server YANG data model\&. 
.br
\fIserver_path\fP Optional parameter to specify path to the transport server\&. If not specified, the function get transport protocol according to value set by \fBnc_session_transport()\fP (default value is SSH transport)\&. For the NC_TRANSPORT_SSH the '/usr/sbin/sshd' path is used (OpenSSH server), in case of NC_TRANSPORT_TLS the '/usr/sbin/stunnel' path is used (OpenSSL server)\&. 
.br
\fIargv\fP List of arguments to be used by execv() when starting the server specified in server_path parameter\&. If server_path not specified (NULL), argv is ignored\&. Remember, that the server is supposed to read data from stdin and write data to stdout (inetd mode)\&. So, for example sshd is running with -i option\&. 
.br
\fIcom_socket\fP If not NULL, function returns TCP socket used for Call Home connection\&. Caller is supposed to close returned socket when it is no more needed\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
-1 on error\&. In case of success, function forks the current process running the transport protocol server and returns its PID\&. 
.RE
.PP

.SS "int nc_callhome_listen (unsigned intport)"

.PP
Start listening on client side for incoming Call Home connection\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIport\fP Port number where to listen\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE on error\&. 
.RE
.PP

.SS "int nc_callhome_listen_stop (void)"

.PP
Stop listening on client side for incoming Call Home connection\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE if libnetconf is not listening\&. 
.RE
.PP

.SS "struct nc_mngmt_server* nc_callhome_mngmt_server_add (struct nc_mngmt_server *list, const char *host, const char *port)"

.PP
Add a new management server specification to the end of a list\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIlist\fP Current list where the server description will be added\&. If NULL, a new list is created and returned by the function\&. 
.br
\fIhost\fP Host name of the management server\&. It specifies either a numerical network address (for IPv4, numbers-and-dots notation as supported by inet_aton(3); for IPv6, hexadecimal string format as supported by inet_pton(3)), or a network host-name, whose network addresses are looked up and resolved\&. 
.br
\fIport\fP Port of the management server\&. If this argument is a service name (see services(5)), it is translated to the corresponding port number\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
NULL on error, created/modified management servers list\&. 
.RE
.PP

.SS "int nc_callhome_mngmt_server_free (struct nc_mngmt_server *list)"

.PP
Free a management server description structure(s)\&. The function doesn't free only the item refered by given pointer, but the complete list of management servers is freed\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIlist\fP List of management servers to be freed\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE\&. 
.RE
.PP

.SS "struct nc_mngmt_server* nc_callhome_mngmt_server_getactive (struct nc_mngmt_server *list)"

.PP
Searches for the item from the list, which was marked and used by the last call to \fBnc_callhome_connect()\fP to a successfully establish Call Home connection\&. 
.PP
\fBParameters:\fP
.RS 4
\fIlist\fP List of management servers\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Pointer to the last connected management server\&. 
.RE
.PP

.SS "int nc_callhome_mngmt_server_rm (struct nc_mngmt_server *list, struct nc_mngmt_server *remove)"

.PP
Remove the specified management server description from the list\&. To make this function available, you have to include \fBlibnetconf_ssh\&.h\fP or \fBlibnetconf_tls\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIlist\fP Management servers list to be modified\&. 
.br
\fIremove\fP Management server to be removed from the given list\&. The structure itself is not freed, use \fBnc_callhome_mngmt_server_free()\fP to free it after calling \fBnc_callhome_mngmt_server_rm()\fP\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libnetconf from the source code\&.
